/*
 * Copyright 2011-2012 by The Regents of the University of California Licensed
 * under the Apache License, Version 2.0 (the "License"); you may not use this
 * file except in compliance with the License. you may obtain a copy of the
 * License from
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package edu.ucsd.db.bassarisk.indexer.api;

import java.io.InputStream;

/**
 * <p>
 * An iterable corpus of text-containing artifacts or a split thereof.
 * 
 * <p>
 * The ICorpus interface should be implemented for each type of text containing
 * corpus that is fed into the Bassarisk indexer tool. The ICorpus
 * implementation must understand how to split the input stream into individual
 * artifacts for further processing.
 * 
 * <p>
 * At issue is the distinction between an "artifact" and a "corpus". A corpus
 * may consist of many artifacts, or only a single large artifact. Importantly,
 * an artifact is the smallest piece of structure that is self contained. E.g.:
 * one XML file, one HTML page, one news article, one PDF. The best breakdown is
 * collection specific, so implementors should use their own judgment.
 * 
 * @see edu.ucsd.db.bassarisk.indexer.ITextArtifact
 * 
 * @author nbales@ucsd.edu
 */
public interface ICorpus extends Iterable<ITextArtifact> {

  /**
   * Initializes a new corpus or corpus shard from an input stream.
   * 
   * @param in
   *          An input stream used to initialize the corpus. This may contain a
   *          stream of data, a stream of filenames, a stream of URIs, ect.
   */
  void initialize(InputStream in);

}